home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / macros / lollipop / prelim.tex < prev    next >
Text File  |  1993-01-28  |  14KB  |  341 lines

  1. % Prelim.tex copyright 1992 Victor Eijkhout
  2. %
  3. \Chapter[chap:prelim] Preliminaries
  4.  
  5. \Section What is Lollipop?
  6.  
  7. Lollipop is `\TeX\ made easy'. Lollipop is a macro package
  8. that functions as a toolbox for writing \TeX\ macros. It was my
  9. intention to make macro writing so easy that implementing a fully new
  10. layout in \TeX\ would become a matter of less than an hour for an
  11. average document, and that it would be a task that could be
  12. accomplished by someone with only a very basic training in \TeX\
  13. programming.
  14.  
  15. Lollipop is an attempt to make structured text formatting available
  16. for environments where previously only wysiwyg packages could be used
  17. because adapting the layout is so much more easy with them than with
  18. traditional \TeX\ macro packages.
  19.  
  20. \Section But is it compatible?
  21.  
  22. Lollipop, like \LaTeX, is not compatible with plain \TeX. I~don't
  23. consider this a real problem. Most plain \TeX\ commands will work in
  24. \Lollipop\ with the exception of anything output routine related.
  25. (See also below.)
  26.  
  27. \Lollipop\ is also not compatible with \LaTeX, although it has a lot
  28. of the same functionality. There are two reasons why \Lollipop\ still
  29. has a reason for existing, even though \LaTeX\ is used pretty much
  30. all over the scientific world.
  31.  
  32. For one, Lollipop is targeted in part
  33. to different users than the typical plain \TeX\ or
  34. \LaTeX\ user. For another, I~have a vain hope that I~can capture some
  35. of the \LaTeX\ market share. Since developing styles in \Lollipop\ is
  36. so much more easier than in \LaTeX, I~may stand a fighting chance.
  37.  
  38. \SubSection \Lollipop\ and plain \TeX
  39.  
  40. Having said the above, I'll conceded that \Lollipop\ is more
  41. compatible with plain \TeX\ than with \LaTeX. You can use quite some
  42. plain \TeX\ commands in \Lollipop. However, stay away from the
  43. following:\Description\item \cs{everypar}
  44. This one is heavily used by \Lollipop. You may use \cs{EveryPar}
  45. instead, which functions pretty much like \cs{everypar}; see
  46. section~\ref[sec:everypar].\item \cs{output}
  47. Page output is done so very differently from plain \TeX\ that all
  48. commands pertaining to page numbers and head/footlines have been
  49. eradicated. (Well, \cs{pageno} still gives the page number.) See
  50. chapter~\ref[chap:output].
  51.  \>
  52.  
  53. The current version of \Lollipop\ is based on the plain \TeX\ file
  54. that comes with \TeX\ version~3.0.
  55.  
  56. \SubSection \Lollipop\ and \TeX\ programming
  57.  
  58. The tools in \Lollipop\ allow you to program in a simple manner quite
  59. complicated macros. Still you may want to have some knowledge of
  60. ordinary \TeX\ macro programming. If you are just starting in \TeX\
  61. you can pick up the basics from the book by Seroul and
  62. Levy~\bibref[SeLe:book], 
  63. and after that there is the book by
  64. the original author of \TeX~\bibref[Kn:book] and my own \TeX\
  65. reference guide~\bibref[E:book].
  66.  
  67.  \Section How to Use \Lollipop
  68.  
  69. The following files comprise the Lollipop format:
  70. \Ver>
  71.     fonts.tex       lists.tex
  72.     define.tex      heading.tex     lollipop.tex    text.tex
  73.     document.tex    lolplain.tex    output.tex      tools.tex<Rev
  74. and it is assumed that you have a file called \file{hyphen.tex} with
  75. hyphenation patters for the language you are using.
  76.  
  77. Run \IniTeX\ on \file{lollipop.tex}. On some systems \IniTeX\ is
  78. really called that, on others you may have to type \n{tex/i} or
  79. something like that. With Textures on the Macintosh you typeset using
  80. the `VirTeX' format (you can load \Lollipop\ on top of plain \TeX\
  81. if you have an old version,
  82. but you then have to ignore the error message about the \cs{patterns}
  83. command).
  84.  
  85.  This gives, depending on your operating system, output that
  86. looks something like this:
  87.  
  88. \Ver>> initex lollipop
  89. This is TeX, C Version 3.0 (INITEX)
  90. (lollipop.tex (lolplain.tex (hyphen.tex)) (tools.tex) (define.tex) (fonts.tex)
  91. (text.tex) (document.tex) (heading.tex) (output.tex) (lists.tex))
  92. Beginning to dump on file lollipop.fmt
  93.  (format=lollipop 92.5.30)
  94. 3102 strings of total length 41719
  95. 27016 memory locations dumped; current usage is 142&26543
  96. 2076 multiletter control sequences
  97. \font\nullfont=nullfont
  98. ...
  99. 2706 words of font info for 12 preloaded fonts
  100. 17 hyphenation exceptions
  101. Hyphenation trie of length 6075 has 181 ops out of 500
  102.   181 for language 0
  103. No pages of output.
  104. Transcript written on lollipop.log.<Rev
  105.  
  106. As a result of this, you get a file \file{lollipop.fmt} that contains
  107. the Lollipop format. This has to be loaded in \TeX\ everytime you want
  108. to format a file. To process a file, say \file{test.tex}, with
  109. Lollipop you then type:
  110. \Ver>
  111. > tex &lollipop test <Rev
  112. or something like that, depending on local conditions (for Unix you
  113. will have to escape the ampersand).
  114.  
  115. \Section[sec:style-dump] Processing a Lollipop file
  116.  
  117. Files that you make to be processed with Lollipop contain of course
  118. the input text, but they also have to contain the design macros that
  119. determine the layout. There are two possibilities for these design
  120. macros:
  121. \Itemize
  122. \item You can simply put them in the same file, either in the
  123. beginning or wherever they are first needed, or
  124. \item You can put the layout definition in a separate file and make a
  125. new format out of that. For instance, if the layout definition of a
  126. book is complicated, processing it each time will be slow, so you
  127. might put it in a file \file{bookstyle.tex}. \IniTeX\ can load this
  128. definition on top of the Lollipop format:
  129. \Ver>
  130. > tex  &lollipopbookstyle
  131. *\dump<Rev
  132. This gives you a format \file{bookstyle.fmt}, 
  133. which you can use by typing
  134. \Ver>> tex &bookstyle book<Rev
  135. \>
  136.  
  137. Also in the case where the style designer and the style user are on
  138. different levels of \TeX pertise it may be wise to hide the style
  139. definition from the user by making only a format available.
  140.  
  141. \ImpNote
  142. The file \file{lollipop.tex} contains a \cs{dump} command. This is
  143. not the way plain \TeX\ and \LaTeX\ operate, but I~like this better.
  144. \ImpNoteStop
  145.  
  146. If you have used \TeX\ before, you will notice that the page numbers
  147. get reported slightly differently from the usual way. See
  148. section~\ref[sec:page-counter] for the explanation.
  149.  
  150. \Section The errors of \Lollipop / known bugs
  151.  
  152. Since \Lollipop\ is an order of magnitude more powerful
  153. (and hence complicated) than formats such as \LaTeX, its error
  154. messages can also be an order of magnitude more cryptic (see
  155. section~\ref[sec:error-msg] for the possible origin of some of the
  156. more obscure error messages). 
  157.  
  158. Fortunately, \Lollipop\ is also quite a
  159. bit better than existing formats at catching potential errors. Typos
  160. in a style definition will usually lead to warning messages, and also
  161. during run time \Lollipop\ is able to track down ommisions.
  162.  
  163. In addition, you can switch on various trace modes to get more
  164. detailed information about \Lollipop's thought processes. See
  165. chapter~\ref[chap:tracing].
  166.  
  167. These are the known bugs in \Lollipop\ at the moment.
  168.  
  169. \Enumerate\item Local references have been insufficiently tested,
  170. and the code definitely is buggy.
  171. \item The `firstpage' test in the page grids does not work.
  172. \item The table of contents example is slightly wrong.
  173. \item Titles get written to the aux file with double spaces.
  174. This shouldn't cause any problem, but it has to be fixed.
  175. \item Rules in page grids get white space around them.
  176. \item External items shouldn't declare \cs{FooTitle} or 
  177. \cs{FooCounter}.
  178. \item \cs{ToExternalFile} doesn't work.
  179.  \>
  180.  
  181. \Section About this manual
  182.  
  183. This manual consists of a main file \file{manual.tex}, and the
  184. following input files:
  185. \Ver>
  186. titlepag.tex prelim.tex struct.tex head.tex list.tex
  187. out.tex extern.tex opt.tex comm.tex trace.tex appendix.tex<Rev
  188. and the style definition file \file{mandefs.tex}.
  189.  
  190. In addition, you need \file{comment.tex} which is used to format this
  191. manual, and \file{btxmac.tex} for the Bib\TeX\ interface, but these
  192. are not really a part of \Lollipop.
  193.  
  194. If you format this manual (which you'll have to do three times
  195. to get the page numbering and the table of contents straight) you'll
  196. notice something strange. The file \file{example.tex} is read in
  197. many, many times. This is because this manual formats its examples
  198. along the way, first writing them out, and then reading them in to
  199. show both their code and their output. This way it is guaranteed that
  200. the examples in the manual will always work.
  201.  
  202. As a result of formatting this manual you will wind up with, apart
  203. from the usual \file{dvi} and \file{log} file, with \file{manual} files
  204. with extensions \file{aux}, \file{toc}, and \file{imp}; 
  205. \file{oix} and \file{cix} for indexes of options and commands,
  206. and
  207. \file{tct}, file{tix} which are for the examples. For the
  208. bibliography there are the Bib\TeX\ input file \file{manual.bib} and
  209. output file \file{manual.bbl}.
  210.  
  211. This manual needs quite some resources: here's what \TeX\ told me
  212. it needed.
  213. \Ver>Here is how much of TeX's memory you used:
  214.  1259 strings out of 4808
  215.  14894 string characters out of 21967
  216.  62606 words of memory out of 65536
  217.  3042 multiletter control sequences out of 10000
  218.  19 hyphenation exceptions out of 307
  219.  22i,4n,24p,225b,502s stack positions out of 
  220.  200i,60n,60p,5000b,2000s<Rev
  221. This should not need a `Big \TeX', but it comes close.
  222.  
  223. Because of all the examples this manual takes quite some time to
  224. process. A~factor of four over the time for a regular document of
  225. similar length should be expected. Ordinary Lollipop documents will
  226. proceed far faster.
  227.  
  228. \Section The most boring section in this manual
  229.  
  230. There are a few things about \Lollipop\ that I~want to be clear about.
  231.  
  232. \SubSection I am going to hurt you and I am not sorry
  233.  
  234. In the secret handbook for the software industry it says that the
  235. final test phase of a product consists of putting it in stores and
  236. having innocent suckers pay good money for it. (You guessed it, this
  237. is the disclaimer section.) So let me just say that 
  238. \Lollipop\ is probably good for nothing, at least, I~don't claim it
  239. is. And if you hurt yourself by using it, don't blame me. I~warned
  240. you.
  241.  
  242. \SubSection Get a \Lollipop, give one away
  243.  
  244. \Lollipop\ is free of charge. You may copy it
  245. for your own purposes, or give away copies. However, you may not ask
  246. money for it, other than reasonable expenses such as for copying discs
  247. or manuals. If you make changes to \Lollipop, the changed files
  248. should be given a different name, and the fact that they are changed
  249. should be clearly indicated. Although I~retain the copyright, the
  250. rights for non-profit use of \Lollipop\ are granted.
  251.  
  252. The easiest way to get the current copy of \Lollipop\ is to ftp it
  253. from \n{cs.utk.edu} from the directory \n{/pub/eijkhout/tex} where it
  254. is stored as \n{lollipop.tar.Z}. Starting with version 0.93 there
  255. is also a self-extracting Macintosh archive.
  256.  
  257. \SubSection The status of \Lollipop
  258.  
  259. \Lollipop\ is still under development. Although I~will try not to
  260. make any drastic changes in the user interface (this says nothing
  261. about the internals!) I~really cannot guarantee anything.
  262. However, I~do listen to complaints and suggestions. 
  263.  
  264. If you have suggestions or complaints about the
  265. useability of \Lollipop\ or the implementation, feel free to contact
  266. me at \cs{eijkhout@cs.utk.edu} on the Internet. Or send snail mail
  267. to:
  268. \Ver>    Victor Eijkhout
  269.     Department of Computer Science
  270.     University of Tennessee
  271.     107 Ayres Hall
  272.     Knoxville TN 37996
  273.     USA<Rev
  274.  
  275. \SubSection[sec:wish:list] The wish list
  276.  
  277. \Lollipop\ is not quite perfect. Here's a list of things that I~am
  278. going to be adding in the near future. If you want to add items to
  279. this list, just mail me.
  280.  
  281. \Enumerate\item Raggedbottom should really, really be added. Soon!
  282.  
  283. \item Capitalization and initial capping of titles. If a
  284. title appears in mixed case, it should be possible to have it in all
  285. uppercase in running heads. Some code has been disabled now.
  286.  
  287. \item A better multi-column mode.
  288.  
  289. \item Interface to Bib\TeX\ seems to largely in place; what happens
  290. if you don't load btxmac?
  291.  
  292. \item Inserts, in particular footnotes. At the moment floating
  293. figures are entirely lacking. (As a matter of fact, the plain \TeX\
  294. macros are availble, but I'm not telling that.)
  295.  
  296. \item A `nomarks' option to prevent wasting two token lists.
  297. Maybe other recourse saving optio for the expert designer?
  298.  
  299. \item More sophisticated white space right before and after
  300. page breaks. (Use at least so and so much.)
  301.  
  302. \item Dynamic topskip.
  303.  
  304. {\PopIndentLevel\Indent:no The following points are debatable:
  305. maybe I~should just steal a few components from \LaTeX. Maybe this
  306. sort of stuff does not belong in \Lollipop.\par}
  307.  
  308. \item A tabular mode. Personally I~always felt \cs{halign} to be more
  309. than sufficient, but some people seem to think otherwise.
  310.  
  311. \item Maths constructs. Some things in the \cs{eqalign} vein would be
  312. nice.
  313.  
  314. \>
  315.  
  316. \SubSection A bit of history
  317.  
  318. The \Lollipop\ format was begun in late 1989 to typeset my Ph.D.
  319. thesis, `{\Style:italic Vectorizable and Parallelizable
  320. Preconditioners for the Conjugate Gradient Method}'. At that time 
  321. I~was using \TeX\ on an Atari 1040ST.
  322. Loading the style definition for the thesis took about two minutes.
  323. \Lollipop\ was heavily augmented in late 1991 to typeset my book
  324. `{\Style:italic \TeX\ by Topic}', for which I~used Sun~3 and Sun~4
  325. computers. Writing this manual brought \Lollipop\ to its present
  326. state; the first public release (version~0.9) was announced on the
  327. internet in October 1992. At present I~am using Lightning Textures on a
  328. Macintosh Powerbook~145.
  329.  
  330. The name `\cs{Lollipop}' refers to a quote by Alan
  331. Perlis~\bibref[Pe:epigrams], quoted on page 365 of the \TeX
  332. book~\bibref[Kn:book]. In a way it's rather pretentious. The philosophy
  333. of the \cs{Lollipop} format is described~\bibref[EL:Cork,E:Portland].
  334.  
  335. \endinput
  336.  
  337. 92/10/22 historical remark about name added
  338. 92/11/03 section 'Lollipop and plain TeX' added;
  339.          remarks about IniTeX in Textures
  340. 92/11/26 uses bibrefs
  341.